home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / qblibs.arc / QBLIBS.DOC
Encoding:
Text File  |  1987-03-06  |  12.1 KB  |  331 lines
  1.  
  2.  
  3.  
  4.  
  5.        This document provides information on how to create a QuickBASIC library
  6.        of user routines.
  7.  
  8.        One of the features that I found particularly appealing about
  9.        Microsoft's QuickBasic was that the documentation indicated that you
  10.        could create libraries of user routines.  Unfortunately, when I
  11.        attempted to work with libraries I found that I had all sorts of
  12.        problems.  Some of this was probably due to my own ineptitude, and some
  13.        due to Microsoft's documentation.  Assuming that other programmers
  14.        attempting to use QuickBASIC libraries for the first time might
  15.        encounter the same problems, I created this document.
  16.  
  17.        Please note that there is a glossary of terms that I will be using on
  18.        the last page.
  19.  
  20.        There are a few assumptions that I make ...
  21.  
  22.           1. The ultimate goal is to have free-standing programs created using
  23.              the /O compile option with the BCOM20 library, and at the same
  24.              time to be able to use those same routines during development (ie.
  25.              when using the QuickBASIC editor/compile to memory feature).
  26.  
  27.           2. I assume that you have read the QuickBASIC reference manual on
  28.              user libraries.  If you feel as frustrated as I did ... well, at
  29.              least I won't feel that I'm the only one who had problems.
  30.              Hopefully, you should be at the level where you understand that
  31.              when I refer to USERLIB as the library, you realize that this
  32.              could represent any name of your choice.
  33.  
  34.           3. You have used, or at least understand, the "Separate Compilation"
  35.              method as outlined in Microsoft's manual.
  36.  
  37.           4. Your modules are subroutines written using the SUB...END SUB form,
  38.              thus allowing you to pass parameters.
  39.  
  40.        A couple of general points ...
  41.  
  42.           1. QuickBASIC does NOT load USERLIB.EXE automatically as stated in
  43.              the manual .. at least I haven't been able to get it to work, and
  44.              I am using the LIB= function documented in the QuickBASIC manual.
  45.              But then again, you don't actually believe everything you read in
  46.              a manual, do you?.  I suggest that you invoke the library manually
  47.              using the /L option as stated in the QuickBASIC manual; at least
  48.              THAT works.
  49.  
  50.           2. If you have the LIB program from the Microsoft Macro Assembler,
  51.              you'll find it useful for maintaining your libraries.  However, it
  52.              certainly is not required.
  53.  
  54.        It might be useful at this point to look at the diagram at the bottom of
  55.        this document, and to refer to it while reading the following
  56.        descriptions.  In the examples below, the extensions, and sometimes the
  57.        resulting file names, can be provided by the Microsoft programs by
  58.        default.  However, for clarity, I have specified all extensions and
  59.        filenames.
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.        Your modules to be accessed from within QuickBASIC during development
  72.        need to reside in USERLIB.EXE.  To place them in that library ...
  73.  
  74.           1. Compile your routines WITHOUT using the /O option to use the
  75.              BRUN20.LIB.  This can be done either from within QB or using the
  76.              command line method.
  77.  
  78.                  Example : QB module.bas ;
  79.  
  80.           2. Use BUILDLIB to place the resulting .OBJ files into the
  81.              USERLIB.EXE library (note the extension .EXE).  Since BUILDLIB
  82.              creates the library from scratch each time, using the MAKE.EXE
  83.              utility supplied with the Microsoft Macro Assembler can help
  84.              automate this process (if you haven't seen it, MAKE.EXE can
  85.              rebuild the library any time one of the original routines is
  86.              changed).
  87.  
  88.                  Example : BUILDLIB module1.obj+module2.obj,userlib.exe ;
  89.  
  90.           3. Start QB using your library name with the /L option, and the
  91.              routines will be available to you.
  92.  
  93.                  Example : QB /L userlib.exe
  94.  
  95.        Modules that are to be used with your free-standing program are compiled
  96.        differently, and can optionally be stored in a true library.
  97.  
  98.           1. Compile your routines WITH the /O  option to use the BCOM20.LIB.
  99.              This can be done either from within QB or using the command line
  100.              method.
  101.  
  102.                  Example : QB module.bas /O ;
  103.  
  104.           2. If you have it available, you can use the LIB.EXE program supplied
  105.              with the MS Macro Assembler to place the resulting .OBJ files into
  106.              a true USERLIB.LIB library file (note the extension .LIB).
  107.              LIB.EXE can use the MAKE.EXE utility to help automate maintenance
  108.              of this library.
  109.  
  110.                  Example : LIB myprogs.lib +module.obj ;
  111.  
  112.              Note that if you had previously placed MODULE.OBJ in the library,
  113.              the command would be ...
  114.  
  115.                  Example : LIB myprogs.lib -+module.obj ;
  116.  
  117.           3. If you don't have LIB.EXE, you can use the DOS COPY command to
  118.              place a number of
  119.  
  120.        By now you realize that you are going to have two different types of
  121.        .OBJ files.  Those you create from your subroutine compiled WITHOUT the
  122.        /O option to be used in USERLIB.EXE, and those compiled WITH the /O
  123.        option (optionally kept in USERLIB.LIB).
  124.  
  125.        To avoid as much confusion as possible, I rename the .OBJ files created
  126.        for use with USERLIB.EXE as .RUN files since they required the run-time
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.        library.  The only inconvenience is that I have to specify the extension
  138.        when using BUILDLIB.
  139.  
  140.                  Example : QB module1.bas ;
  141.                            REN module1.obj module1.run
  142.                            BUILDLIB module1.run+module2.run,userlib.exe
  143.  
  144.        When linking your free-standing modules, you will need to either specify
  145.        the individual .OBJ files, or, if you used LIB.EXE, the name of the
  146.        library you created.
  147.  
  148.                  Example : LINK
  149.          
  150.                            Object Modules [.OBJ] : main.obj+module1.obj
  151.                            Run File [MAIN.EXE] :
  152.                            List File [NUL.MAP] :
  153.                            Libraries [.LIB] :
  154.  
  155.                  Example : LINK
  156.          
  157.                            Object Modules [.OBJ] : main.obj
  158.                            Run File [MAIN.EXE] :
  159.                            List File [NUL.MAP] :
  160.                            Libraries [.LIB] : userlib
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.        **********************                +--------------------+
  204.        *      PROGRAMS      *                |        FILES       |
  205.        **********************                +--------------------+
  206.        
  207.        
  208.        
  209.                               +------------+
  210.                               | MODULE.BAS |
  211.                               +------------+
  212.                              /              \
  213.                             V                V
  214.        **********************                **********************
  215.        *     QUICKBASIC     *                *      QUICKBASIC    *
  216.        * Compile WITHOUT /O *                *  Compile using /O  *
  217.        **********************                **********************
  218.                  |                                      |
  219.                  V                                      V
  220.        +--------------------+                +--------------------+
  221.        |    MODULE.OBJ      |                |    MODULE.OBJ      |
  222.        +--------------------+                +--------------------+
  223.                  |                          /           .
  224.                  V                         /            .
  225.        **********************             /             .
  226.        *      BUILDLIB      *            /   This path is an alternate
  227.        **********************           /   depending on whether or not
  228.                  |                     +   you own the MS Macro Assembler
  229.                  V                     |                .
  230.        +--------------------+          |                .
  231.        |   USERLIB.EXE      |          |                V
  232.        | for use w/ QBASIC  |          |     **********************
  233.        +--------------------+          |     *         LIB        *
  234.                                        |     **********************
  235.                                        |                .
  236.                                        |                .
  237.                                        |                V
  238.        +--------------------+          |     +--------------------+
  239.        |     MAIN.BAS       |          |     |     USERLIB.LIB    |
  240.        +--------------------+          |     | for use with LINK  |
  241.                  |                     |     +--------------------+
  242.                  V                     +               .
  243.        **********************           \              .
  244.        *     QUICKBASIC     *            \             .
  245.        *  Compile using /O  *             \            .
  246.        **********************              \           .
  247.                 |                           \          .
  248.                 V                            V         V
  249.        +-------------------+                 **********************
  250.        |    MAIN.OBJ       |---------------> *        LINK        *
  251.        +-------------------+                 **********************
  252.                                                         |
  253.                                                         V
  254.                                              +--------------------+
  255.                                              |      MAIN.EXE      |
  256.                                              +--------------------+
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.                                   GLOSSARY OF TERMS
  270.                                            
  271.          .OBJ file - A compiled subroutine or main program prior to linking or
  272.              installing in a library.  THERE ARE TWO DIFFERENT TYPES OF OBJ
  273.              FILES.  One type has been compiled WITH the /O option, the other
  274.              without.
  275.  
  276.          BCOM20.LIB - The Microsoft library supplied with QuickBASIC that
  277.              provides the routines need by free-standing programs.
  278.  
  279.          BRUN20.LIB - The Microsoft library supplied with QuickBASIC that is
  280.              used during the development cycle (editing, compiling to memory,
  281.              etc).  This library is also used if you compile your program but
  282.              do not make it free-standing.
  283.  
  284.          BUILDLIB.EXE - A support program from Microsoft that allows .OBJ files
  285.              to be placed into a library file for use with QuickBASIC during
  286.              development (editing, compiling to memory, etc).
  287.  
  288.          Free-standing module/program - A program or subroutine that has been
  289.              compiled by QuickBASIC using the /O option so that it does not
  290.              require the BRUN20 library.
  291.  
  292.          LIB.EXE - A support program from Microsoft that allows .OBJ files to
  293.              be placed into a library file that can be used with the LINK
  294.              program.
  295.  
  296.          USERLIB.EXE - A file containing a collection of subroutines.  These
  297.              routines are available within QuickBASIC during development
  298.              (editing, compiling to memory, etc).
  299.  
  300.          USERLIB.LIB - A file containing a collection of subroutines.  These
  301.              routines are available to be linked to your separately compiled
  302.              main programs.
  303.  
  304.        ------------------------------------------------------------------------
  305.  
  306.        If you found this to be interest, have any comments or suggestions, or
  307.        tried to follow this but found it too confusing, drop me a note.  In
  308.        particular, please let me know if you have any corrections I need to
  309.        make!
  310.  
  311.        It would be nice to know if someone actually reads this.
  312.  
  313.                  Robert Potter
  314.                  76266,2233
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.